home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cpp_libs / nihcl-30.lha / nihcl-3.0 / doc / readme.tr < prev   
Text File  |  1990-05-25  |  58KB  |  2,615 lines
  1. .ig
  2.     A complete rewrite of the texttroff macro package.
  3.     It would be loosely modelled after the -ms macros
  4.  
  5.     main concept is to separate the elements of the page,
  6.     so a trap for the footer and a trap for the header separatly
  7.  
  8.     Also all default values are in well known registers,
  9.     initialized by the .IZ macro
  10. ..
  11. .\"
  12. .    \" IZ - initialize. Provide some default settings
  13. .de IZ
  14. .nr PS \n(.p    \" pointsize
  15. .nr VS \n(.v    \" linespacing
  16. .nr HM 1i    \" header margin
  17. .nr FM 1i    \" footer margin
  18. .nr LL \n(.l    \" line length
  19. .nr IN 36p    \" indent to allow outdenting headers
  20. .nr LT \n(.l-\n(INu    \" title length
  21. .\" trap setting
  22. .\"
  23. .\" for the top of page
  24. .wh 0 NP
  25. .\" for dealing with footnotes
  26. .wh 14i FO    \" footer trap, temp position
  27. .    \" to process footnote overflow, we fire this trap
  28. .    \" the trap for FO will be moved way up so we will fire
  29. .    \" this one when FO is putting the footnote out
  30. .wh -\\n(FMu Fx
  31. .    \" Now install FO on top of this position so it
  32. .    \" will be fired when no footnote needs to be processed
  33. .ch -\\n(FMu FO
  34. .\" for the bottom tittle
  35. .wh -\\n(FMu/2u BT
  36. ..
  37. .\"
  38. .    \" TA - set tabstops
  39. .de TA
  40. .ta \\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu +\\n(ENu
  41. ..
  42. .\"
  43. .    \" RS - Reset.    Bring troff into a known state
  44. .de RS
  45. .ps \\n(PS
  46. .vs \\n(VSu
  47. .ll \\n(LLu
  48. .lt \\n(LTu
  49. .in \\n(INu
  50. .po \\n(POu
  51. .nr FS \\n(VSu/4u    \" footnote separation
  52. .nr F 0 1        \" for footnote numbering
  53. .ev 1
  54. .    \" where footnotes are processed
  55. .ps \\n(PS-2
  56. .vs (\\n(VSu-2p)u
  57. .ll \\n(LLu-\\n(INu
  58. .ev
  59. .ev 2
  60. .    \" where the table of contents is stored
  61. .ps \\n(PS
  62. .vs \\n(VSu
  63. .ev
  64. .TA
  65. ..
  66. .\"
  67. .    \" string for footnote numebering. Note that the increment takes place here
  68. .    \" note that Fn is defined in texttroff to get the body font
  69. .ds * \v'-.3v'\\*(Fn\s-3\\n+F\s0\fP\v'.3v'
  70. .ig
  71.     Running headers & footers.
  72.     These will be called from the header & footer macro
  73.     halfway the current margins in the macros PT & BT
  74.     Note that we don't use the page counter (%) directly.
  75.     We stick the value in register PN.
  76.     This allows for changing the format of the page number with
  77.     the .af request without screwing up troff
  78.  
  79.     We will enable the possibility to change on odd & even pages eventually
  80. ..
  81. .\"
  82. .    \" PT - Page Trap & Bottom Trap macro
  83. .de PT
  84. .if \\n(Tc=2 .br
  85. .po +\\n(INu
  86. .pc %
  87. .ie \\n(Tc=3 .nr PN \\n%-\\n(Pc
  88. .el .nr PN \\n%
  89. .nr Pn \\n%
  90. .if \\n(Pn>1 .if e .tl '\\*(LT'\\*(CT'\\*(RT'
  91. .if \\n(Pn>1 .if o .tl '\\*(RT'\\*(CT'\\*(LT'
  92. .po
  93. ..
  94. .    \" default footer string definitions 
  95. .po +\\n(INu
  96. .de BT
  97. .nr PF \\n(.f
  98. .nr PX \\n(.s
  99. .ft 1
  100. .ps \\n(PS
  101. .lt \\n(LTu
  102. .po +\\n(INu
  103. .if e .tl '\\*(LB'\\*(CB'\\*(RB'
  104. .if o .tl '\\*(RB'\\*(CB'\\*(LB'
  105. .ft \\n(PF
  106. .ps \\n(PX
  107. .po
  108. .if \\n(Tc=2 \{\
  109. .    nr Pc \\n%
  110. .    nr Tc 3
  111. .    af PN i
  112. .    TC
  113. .\}
  114. ..
  115. .    \" default header string definitions
  116. .ds CT - \\n(PN -
  117. .\"
  118. .\"
  119. .    \" NP - header macro
  120. .ig
  121.     print the header halfway the margins
  122.     only print when not on the first page
  123. ..
  124. .de NP
  125. .\".tm in NP page \\n% PO \\n(PO .o \\n(.o
  126. .nr PF \\n(.f
  127. .nr PX \\n(.s
  128. .ft 1
  129. .ps \\n(PS
  130. 'sp |\\n(HMu/2u
  131. .if !\\n%=0 .PT
  132. .ps \\n(PX
  133. .ft \\n(PF
  134. 'sp |\\n(HMu
  135. .nr Fc 0 1    \" init footnote count
  136. .nr Fp 0-\\n(HMu    \" current footer place
  137. .ch FO -\\n(HMu    \" reset footer trap
  138. .if \\n(dn .Fz    \" proces left over footnote
  139. .ns    \" no space mode
  140. ..
  141. .\"
  142. .    \" FO - footer macro
  143. .de FO
  144. .nr dn 0    \" zero last diversion size
  145. .if \\n(Fc \{\
  146. .    ev 1        \" expand footnotes in ev1
  147. .\".if '\\n(.z'Fy' .tm in overlow .i \\n(.i
  148. .in \\n(INu        \" set indentation to the one for the page
  149. .    nf        \" retain vertical size
  150. .    FN        \" dump the footnotes
  151. .            \" remove them; Don't put a comment on the next line
  152. .            \" with .rm, some troffs go into an infinite loop
  153. .    rm FN
  154. .\".if '\\n(.z'Fy' .tm in overlow .i \\n(.i
  155. .    if \\n(.zFy .di    \"end overflow diversion
  156. .    nr Fc 0        \" disable fx
  157. .    in 0        \" clear indentation
  158. .ev
  159. .\}
  160. .        \" pop environment
  161. 'bp
  162. ..
  163. ."
  164. .\"    Fx - process footnote overflow
  165. .\"
  166. .de Fx
  167. .if \\n(Fc \{\
  168. .    \" the foonote didn't fit so
  169. .di Fy    \" divert the overflow into Fy (we are still in env 1, so nofill mode)
  170. .    \" since we are in nofill mode and head indentation set,
  171. .in 0    \" set no indentation, so we don't indent twice
  172. .\}
  173. ..
  174. .\"
  175. .\"    FS - Footnote Start
  176. .de FS
  177. .da FN    \" divert (or append) footnote
  178. .ev 1    \" in environment 1
  179. .if \\n+(Fc=1 .FM    \" if first include seperator
  180. .fi    \" process in fill mode
  181. .if !\\n(Fo .FP    \" Footnote paragraph if not processing overflow
  182. ..
  183. .\"
  184. .    \" FP - footnote paragraph
  185. .de FP
  186. .sp \\n(FSu
  187. \v'-.3'\s-3\\nF\s0\v'.3'\|\c
  188. ..
  189. .\"
  190. .\"    FE - Footnote End
  191. .de FE
  192. .br        \" flush the output buffer
  193. .nr Sv \\n(.v    \" save baselinespacing of this env
  194. .ev        \" pop env
  195. .di        \" end the diversion
  196. .nr Fp -\\n(dn    \" new footer position
  197. .if \\n(Fc=1 .nr Fp -(\\n(.v-\\n(Sv)    \" For Separator
  198. .ch FO \\n(Fpu    \" change the trap, Fp is negative
  199. .    \" See whether the stuff really fits.
  200. .    \"if not change trap and we overflow
  201. .if (\\n(nl+1v)>(\\n(.p+\\n(Fp) .ch FO \\n(nlu+1v    \" it didn't fit,
  202. .    \" so fire the FO macro on the next line
  203. ..
  204. .\"
  205. .    \" FM - footnote separator one inch line
  206. .de FM
  207. \l'1i'
  208. .br
  209. ..
  210. .\"
  211. .\"    Fz - process footnote overflow
  212. .de Fz
  213. .nr Fo 1
  214. .FS
  215. .nf    \" is already processed, so keep size
  216. .Fy    \" where Fx put it
  217. .nr Fo 0
  218. .FE
  219. ..
  220. .\"
  221. .\"    HE - next thing will be a header
  222. .\" minimalistic widow control in HE macro.
  223. .\" We aks for a couple of lines with the .ne statement, will trigger the
  224. .\" bottom of page trap on the moment when there is no space 
  225. .de HE
  226. .ne 1.5i
  227. ..
  228. .\"
  229. .\"    IC - in table of contents
  230. .\"    $1 type of header $3 number, $2 text
  231. .\"
  232. .de IC
  233. .nr Tc 1    \"flag that we have a contents
  234. .ev 2
  235. .if !'\\$3'NO' \{\
  236. .    nr Tx \w'\\$3\0'u
  237. .    if \\n(Tx>\\n(Ta .nr Ta \\n(Tx
  238. .\}
  239. .nr Tp \w'\0\\n(PN'u
  240. .da Tc
  241. \\!.xx "\\$1" "\\$2" \\$3 \\n(PN
  242. .br
  243. .di
  244. .ev
  245. ..
  246. .\"
  247. .\"    An item in the table of contents
  248. .de xx
  249. .if \\$1=1 .sp .5
  250. .ie !'\\$3'NO' \\$3\t\\$2\a\t\\$4
  251. .el .ie \\n(Ta \&\t\\$2\a\t\\$4
  252. .el \&\\$2\a\t\\$4
  253. ..
  254. .\"    EM
  255. .\" check for work at end of file
  256. .de EM
  257. .if \\n(Tc \{\
  258. \c
  259. .nr Tc 2
  260. .\}
  261. .\"tm EM called, Tc: \\n(Tc
  262. ..
  263. .\" do the things we want at the end of the paper
  264. .de TC
  265. .\"tm TC called
  266. 'bp
  267. .ft B
  268. .\".tm tabel of contents
  269. .ce
  270. .rs
  271. .sp
  272. .ti -\\n(INu
  273. \s+2Table of Contents\s0
  274. .sp 2
  275. .ft R
  276. .nf
  277. .ev 2
  278. .    \" where the table of contents is stored
  279. .nf
  280. .nr Tb \\n(LLu-\\n(Tpu-\\n(INu
  281. .nr c \w'1.1.1.1\0'u
  282. .ie \\n(Ta .ta \\n(Tau \\n(Tbu \\n(LLu-\\n(INuR
  283. .el .ta \\n(Tbu \\n(LLu-\\n(INuR
  284. .in \\n(INu
  285. .Tc
  286. .ev
  287. ..
  288. .\"
  289. .\"    set end macro
  290. .em EM
  291. .\" in texttroff .IZ
  292. .\" in texttroff .RS
  293. .\"
  294. .\"
  295. .\"
  296. .\" Begin of the PSmacros, coutesy of fred hansen (I believe)
  297. .\"
  298. .nr zT 0
  299. .if  "\*(.T"postscript"  'nr zT 1
  300. .if  "\*(.T"psc"  'nr zT 1
  301. .de PB
  302. 'ne \\$2p
  303. 'nr zw \\n(.l-\\n(.k-1m-\\$1p
  304. 'nr zH \\n(.k
  305. 'nr zV \\n(.d
  306. 'if  \\n(zT  \\{\\
  307. 'ie  !\\n(zw  \\{\\
  308. 'nr zx \\n(.l-\\$1p-10m
  309. 'nr zV \\n(zV+1v
  310. .sp 0
  311. \\v'-.75v'\\ \\v'+.75v'\\c\\}
  312. 'el \\{\\
  313. 'nr zx \\n(zw-10m
  314. \\v'-.75v'\\ \\v'+.75v'\\c\\}
  315. .sp |\\n(zVu
  316. 'if ((\\n(zx<=0)&(\\$2p>0.75v)) \\x'\\$2p-0.75v'\\c
  317. \\!%
  318. \\!%!
  319. \\!  PB
  320. 'if \\n(.j=3 \\{\\
  321. \\!    /troffadjust { neg 2 idiv } def
  322. 'ss\\}
  323. 'if \\n(.j=5 \\{\\
  324. \\!    /troffadjust { neg } def
  325. 'ss\\}
  326. 'if \\n(.j<3 \\{\\
  327. \\!    /troffadjust { pop 0 } def
  328. 'ss\\}\\}
  329. ..
  330. .de PE
  331. 'if \\n(zT \\{\\
  332. \\!  PE
  333. \\!.
  334. 'ie \\n(zx \\{\\
  335. 'if (\\$2p>0.75v) \\x'\\$2p-0.75v'\\c
  336. \\h'-\\n(.ku+\\n(zHu+\\$1p'\\c\\}
  337. 'el  .br\\}
  338. 'if !\\n(zT \\{\\
  339. 'if  !\\n(zw  \\{\\
  340.  \\h'-\\n(.k'\\ \\h'-\\n(.w'\\c
  341. .sp -1\\}
  342. \\x'\\$2p-0.75v'\\v'-.75v'\\D'l \\$1p \
  343. 0.0i'\\D'l 0.0i \\$2p'\\D'l -\\$1p 0.0i'\\D'l 0.0i \
  344. -\\$2p'\\v'+.75v'\\h'\\$1p'\\c\\}
  345. ..
  346. .\"
  347. .\" End of PSmacros
  348. .\"
  349. .\"
  350. .\" ix macro for index production. 
  351. .\"
  352. .de ix
  353. .ie '\\n(.z'' .tm ix: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9    \\n%
  354. .el \\!.ix \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9    \\n%
  355. ..
  356. .\"
  357. .\" End of ix macro
  358. .\"
  359. .IZ
  360. .nr IN 36p
  361. .nr LT 432p
  362. .nr PO 54p
  363. .br
  364. .ad b
  365. 'ft R
  366. .nr PS 12
  367. .ps \n(PS
  368. .nr VS 14p
  369. .vs \n(VSu
  370. .nr EN 8n
  371. .sp 0.5i
  372. .nr DP 0
  373. .ds Fn \fR
  374. .ds HF R
  375. .nr HS \n(.s
  376. .ds FF R
  377. .nr FS \n(.s
  378. .RS
  379. .nh
  380. .OC
  381. .ds Cl Release Notes
  382. .ll 6.75i
  383. .po .75i
  384. .nr Dr 1
  385. .nr DP 0
  386. .ds BU \s-2\(bu\s0
  387. .ds EM \(em
  388. .if\n(mo-0 .ds DT January
  389. .if\n(mo-1 .ds DT February
  390. .if\n(mo-2 .ds DT March
  391. .if\n(mo-3 .ds DT April
  392. .if\n(mo-4 .ds DT May
  393. .if\n(mo-5 .ds DT June
  394. .if\n(mo-6 .ds DT July
  395. .if\n(mo-7 .ds DT August
  396. .if\n(mo-8 .ds DT September
  397. .if\n(mo-9 .ds DT October
  398. .if\n(mo-10 .ds DT November
  399. .if\n(mo-11 .ds DT December
  400. .asDT " \n(dy, 19\n(yr
  401. .ds LT \*(Cl
  402. .ds CT NIH Class Library Revision 3.0
  403. .ds RT \*(Cl
  404. .ds LB Page \\n%
  405. .ds RB \*(DT
  406. .tl `\*(LT`\*(CT`\*(RT`
  407. .ps
  408. .ft P
  409. 'sp 0.3i
  410. .OC
  411. .br
  412. .TA
  413. .HE
  414. .br
  415. .ad l
  416. 'ft B
  417. .ps 14
  418. .OC
  419. .sv 1
  420. .vs 16
  421. INTRODUCTION
  422. .ad b
  423. 'ft R
  424. .ps 12
  425. .OC
  426. .sp 1
  427. .vs 14
  428. These are the release notes for Revision 3.0 of the NIH Class Library, the version 
  429. of the library described by our book \fIData Abstraction and Object-Oriented Programming 
  430. in C++\fR by Keith E. Gorlen, Sanford M. Orlow, and Perry S. Plexico (ISBN 0471 92346 
  431. X), published by John Wiley and Sons.
  432. .OC
  433. .sp 1
  434. This release of the NIH Class Library contains the following classes:\fB
  435. .OC
  436. .sp 1
  437. NIHCL\fR---Library Static Member Variables and Functions
  438. .OC
  439. .br
  440.     \fBObject\fR---Root of the NIH Class Library Inheritance Tree
  441. .OC
  442. .br
  443.         \fBBitset\fR---Set of Small Integers (like Pascal's type SET)
  444. .OC
  445. .br
  446.         \fBClass\fR---Class Descriptor
  447. .OC
  448. .br
  449.         \fBCollection\fR---Abstract Class for Collections
  450. .OC
  451. .br
  452.             \fBArraychar\fR---Byte Array
  453. .OC
  454. .br
  455.             \fBArrayOb\fR---Array of Object Pointers
  456. .OC
  457. .br
  458.             \fBBag\fR---Unordered Collection of Objects
  459. .OC
  460. .br
  461.             \fBSeqCltn\fR---Abstract Class for Ordered, Indexed Collections
  462. .OC
  463. .br
  464.                 \fBHeap\fR---Min-Max Heap of Object Pointers
  465. .OC
  466. .br
  467.                 \fBLinkedList\fR---Singly-Linked List
  468. .OC
  469. .br
  470.                 \fBOrderedCltn\fR---Ordered Collection of Object Pointers
  471. .OC
  472. .br
  473.                     \fBSortedCltn\fR---Sorted Collection
  474. .OC
  475. .br
  476.                         \fBKeySortCltn\fR---Keyed Sorted Collection
  477. .OC
  478. .br
  479.                 \fBStack\fR---Stack of Object Pointers
  480. .OC
  481. .br
  482.             \fBSet\fR---Unordered Collection of Non-Duplicate Objects
  483. .OC
  484. .br
  485.                 \fBDictionary\fR---Set of Associations
  486. .OC
  487. .br
  488.                     \fBIdentDict\fR---Dictionary Keyed by Object Address
  489. .OC
  490. .br
  491.                 \fBIdentSet\fR---Set Keyed by Object Address
  492. .OC
  493. .br
  494.         \fBDate\fR---Gregorian Calendar Date
  495. .OC
  496. .br
  497.         \fBFDSet\fR---Set of File Descriptors for Use with \fCselect(2)\fR System Call
  498. .OC
  499. .br
  500.         \fBFloat\fR---Floating Point Number
  501. .OC
  502. .br
  503.         \fBFraction\fR---Rational Arithmetic
  504. .OC
  505. .br
  506.         \fBInteger\fR---Integer Number Object
  507. .OC
  508. .br
  509.         \fBIterator\fR---Collection Iterator
  510. .OC
  511. .br
  512.         \fBLink\fR---Abstract Class for LinkedList Links
  513. .OC
  514. .br
  515.             \fBLinkOb\fR---Link Containing Object Pointer
  516. .OC
  517. .br
  518.             \fBProcess\fR---Co-routine Process Object
  519. .OC
  520. .br
  521.                 \fBHeapProc\fR---Process with Stack in Free Store
  522. .OC
  523. .br
  524.                 \fBStackProc\fR---Process with Stack on \fCmain()\fR Stack
  525. .OC
  526. .br
  527.         \fBLookupKey\fR---Abstract Class for Dictionary Associations
  528. .OC
  529. .br
  530.             \fBAssoc\fR---Association of Object Pointers
  531. .OC
  532. .br
  533.             \fBAssocInt\fR---Association of Object Pointer with Integer
  534. .OC
  535. .br
  536.         \fBNil\fR---The Nil Object
  537. .OC
  538. .br
  539.         \fBPoint\fR---X-Y Coordinate Pair
  540. .OC
  541. .br
  542.         \fBRandom\fR---Random Number Generator
  543. .OC
  544. .br
  545.         \fBRange\fR---Range of Integers
  546. .OC
  547. .br
  548.         \fBRectangle\fR---Rectangle Object
  549. .OC
  550. .br
  551.         \fBScheduler\fR---Co-routine Process Scheduler
  552. .OC
  553. .br
  554.         \fBSemaphore\fR---Process Synchronization
  555. .OC
  556. .br
  557.         \fBSharedQueue\fR---Shared Queue of Objects
  558. .OC
  559. .br
  560.         \fBString\fR---Character String
  561. .OC
  562. .br
  563.             \fBRegex\fR---Regular Expression
  564. .OC
  565. .br
  566.         \fBTime\fR---Time of Day
  567. .OC
  568. .br
  569.         \fBVector\fR---Abstract Class for Vectors
  570. .OC
  571. .br
  572.             \fBBitVec\fR---Bit Vector
  573. .OC
  574. .br
  575.             \fBByteVec\fR---Byte Vector
  576. .OC
  577. .br
  578.             \fBShortVec\fR---Short Integer Vector
  579. .OC
  580. .br
  581.             \fBIntVec\fR---Integer Vector
  582. .OC
  583. .br
  584.             \fBLongVec\fR---Long Integer Vector
  585. .OC
  586. .br
  587.             \fBFloatVec\fR---Floating Point Vector
  588. .OC
  589. .br
  590.             \fBDoubleVec\fR---Double-Precision Floating Point Vector
  591. .OC
  592. .br
  593.     \fBOIOifd\fR---File Descriptor Object I/O \fCreadFrom()\fR Formatting
  594. .OC
  595. .br
  596.     \fBOIOin\fR---Abstract Class for Object I/O \fCreadFrom()\fR Formatting
  597. .OC
  598. .br
  599.         \fBOIOistream\fR---Abstract Class for Stream Object I/O \fCreadFrom()\fR Formatting
  600. .OC
  601. .br
  602.             \fBOIOnihin\fR---Stream Object I/O \fCreadFrom()\fR Formatting
  603. .OC
  604. .br
  605.     \fBOIOofd\fR---File Descriptor Object I/O \fCstoreOn()\fR Formatting
  606. .OC
  607. .br
  608.     \fBOIOout\fR---Abstract Class for Object I/O \fCstoreOn()\fR Formatting
  609. .OC
  610. .br
  611.         \fBOIOostream\fR---Abstract Class for Stream Object I/O \fCstoreOn()\fR Formatting
  612. .OC
  613. .br
  614.             \fBOIOnihout\fR---Stream Object I/O \fCstoreOn()\fR Formatting
  615. .OC
  616. .br
  617.     \fBReadFromTbl\fR---Tables used by Object I/O \fCreadFrom()\fR
  618. .OC
  619. .br
  620.     \fBStoreOnTbl\fR---Tables used by Object I/O \fCstoreOn()\fR
  621. .HE
  622. .br
  623. .ad l
  624. 'ft B
  625. .ps 14
  626. .OC
  627. .sp 2
  628. .vs 16
  629. CHANGES BETWEEN OOPS V2R2 AND NIHCL R3.0
  630. .ad b
  631. 'ft R
  632. .ps 12
  633. .OC
  634. .sp 1
  635. .vs 14
  636. This section highlights the most significant changes that have been made since the 
  637. previous release.  It is by no stretch of the imagination complete.
  638. .HE
  639. .br
  640. .ad l
  641. 'ft B
  642. .OC
  643. .sp 1
  644. Library name changed from "OOPS" to "NIH Class Library" (NIHCL)
  645. .ad b
  646. 'ft R
  647. .OC
  648. .sp 1
  649. Since there's too many things called "OOPS" these days, we've changed the name of 
  650. our library to the "NIH Class Library".  All file and C++ names containing "OOPS" have 
  651. been changed, often just by substituting "NIHCL" for "OOPS".
  652. .HE
  653. .br
  654. .ad l
  655. 'ft B
  656. .OC
  657. .sp 1
  658. Class NIHCL
  659. .ad b
  660. 'ft R
  661. .OC
  662. .sp 1
  663. With the introduction of static member functions and (useful) static member variables 
  664. in R2.0, it is now possible to eliminate most global names.  In R3.0, we've gathered 
  665. many previously global functions and variables and made them static members of a new 
  666. class, \fCNIHCL\fR, which is the base class of \fCObject\fR.  Here's a list of the public functions:
  667. 'in 72p
  668. .br
  669. .ad l
  670. 'ft C
  671. .ps 10
  672. .OC
  673. .sp 1
  674. .vs 12
  675. static class NIHCL {
  676. .OC
  677. .br
  678. // ...
  679. .OC
  680. .br
  681. public:             // static member functions
  682. .OC
  683. .br
  684.     static unsigned char charBitMask(int i);
  685. .OC
  686. .br
  687.     static unsigned short shortBitMask(int i);
  688. .OC
  689. .br
  690.     static unsigned int intBitMask(int i);
  691. .OC
  692. .br
  693.     static unsigned char bitCount(int i);
  694. .OC
  695. .br
  696.     static unsigned char bitReverse(int i);
  697. .OC
  698. .br
  699.     static void initialize();           // library initialization
  700. .OC
  701. .br
  702.     static bool initialized();          // library initialized?
  703. .OC
  704. .br
  705.     static void setError(int error, int sev ...);
  706. .OC
  707. .br
  708. } NIHCL_init;
  709. 'in 36p
  710. .ad b
  711. 'ft R
  712. .ps 12
  713. .OC
  714. .sp 1
  715. .vs 14
  716. Since all NIH Library classes inherit these members, their member functions can use 
  717. these names without needing to specify a scope qualifier, except to resolve ambiguities.  
  718. However, non-member functions and member functions of classes not derived from \fCNIHCL\fR 
  719. can access them with the \fCNIHCL\fR scope qualifier; for example:
  720. 'in 72p
  721. .br
  722. .ad l
  723. 'ft C
  724. .ps 10
  725. .OC
  726. .sp 1
  727. .vs 12
  728. NIHCL::setError(ERROR_CODE, DEFAULT);
  729. 'in 36p
  730. .ad b
  731. 'ft R
  732. .ps 12
  733. .HE
  734. .br
  735. .ad l
  736. 'ft B
  737. .OC
  738. .sp 1
  739. .vs 14
  740. Optional support for multiple inheritance
  741. .ad b
  742. 'ft R
  743. .OC
  744. .sp 1
  745. The NIH Class Library can be compiled to support Multiple Inheritance (MI) by defining 
  746. the preprocessor symbol \fCMI\fR.  \fIAll classes linked together in a program must all have 
  747. been compiled with the same \f(COMI\fI option setting\fR.  The major effect of this switch is 
  748. that all classes derived from \fCObject\fR specify it as a virtual base class.  Since C++ 
  749. does not permit a pointer to a virtual base class to be cast down to a pointer to a 
  750. derived class, the new \fCDECLARE_MEMBERS\fR macro defines an overloaded family of static 
  751. member functions named \fCcastDown()\fR that can perform this conversion. (If \fCMI\fR is not enabled, \fC
  752. castDown()\fR becomes an ordinary pointer cast.)
  753. .OC
  754. .sp 1
  755. The \fCcastDown()\fR functions all call the function \fC_castDown()\fR to perform the pointer 
  756. conversion.  If a class has only a single base class, it uses the \fCDEFINE_CLASS\fR and \fC
  757. DEFINE_ABSTRACT_CLASS\fR preprocessor macros as before, and these generate an  implementation 
  758. of \fC_castDown()\fR suitable for the single inheritance case.  If a class has multiple base 
  759. classes, it uses the new \fCDEFINE_CLASS_MI\fR and \fCDEFINE_ABSTRACT_CLASS_MI\fR macros, which 
  760. do \fInot\fR generate \fC_castDown()\fR---the class provider must supply a definition as described 
  761. in \fCTemplate_c\fR.
  762. .OC
  763. .sp 1
  764. All \fCreadFrom()\fR constructors must specify the \fCreadFrom()\fR constructor for the virtual 
  765. base class \fCObject\fR in their initialization lists when \fCMI\fR is enabled.  See \fCTemplate_h\fR 
  766. for details.
  767. .OC
  768. .sp 1
  769. If you use virtual base classes in conjunction with the NIH Class Library, you must 
  770. take care when implementing the \fCdeepCopy()\fR and \fCstoreOn()\fR operations that a virtual 
  771. base class's member variables are only deepened or stored once.  The library provides 
  772. the functions \fCdeepenVBase()\fR and \fCstoreVBaseOn()\fR to help with this.  Call \fCdeepenVBase()\fR 
  773. instead of \fCdeepenShallowCopy()\fR to deepen the member variables of a virtual base class, 
  774. and call \fCstoreVBaseOn()\fR instead of \fCstorer()\fR to store the member variables of a virtual 
  775. base class.
  776. .br
  777. .ad l
  778. 'ft CB
  779. .OC
  780. .sp 1
  781. DECLARE_MEMBERS
  782. .HE
  783. 'ft B
  784. \c
  785.  macro
  786. .ad b
  787. 'ft R
  788. .OC
  789. .sp 1
  790. The new DECLARE_MEMBERS preprocessor macro generates the declarations for the class 
  791. descriptor and most of the member functions that all NIH Library classes must provide, 
  792. including:
  793. 'in 72p
  794. .br
  795. .ad l
  796. 'ft C
  797. .ps 10
  798. .OC
  799. .sp 1
  800. .vs 12
  801. private:
  802. .OC
  803. .br
  804.     static Class classDesc;        // class descriptor
  805. .OC
  806. .br
  807. public:\f(CO
  808. .OC
  809. .br
  810.     classname\fC* castDown(Object*);
  811. .OC
  812. .br
  813.     const \f(COclassname\fC* castDown(const Object*);
  814. .OC
  815. .br
  816.     \f(COclassname\fC& castDown(Object&);
  817. .OC
  818. .br
  819.     const \f(COclassname\fC& castDown(const Object&);
  820. .OC
  821. .br
  822.     static const Class* desc();        // return class descriptor
  823. .OC
  824. .br
  825.     static \f(COclassname\fC* readFrom(OIOin&);
  826. .OC
  827. .br
  828.     static \f(COclassname\fC* readFrom(OIOifd&);
  829. .OC
  830. .br
  831.     \f(COclassname\fC(OIOin&);            // readFrom() constructors
  832. .OC
  833. .br
  834.     \f(COclassname\fC(OIOout&);
  835. .OC
  836. .br
  837.     virtual const Class* isA() const;
  838. .OC
  839. .br
  840.     virtual Object* shallowCopy() const;
  841. .OC
  842. .br
  843.     virtual void* _castdown(const Class&) const;
  844. .OC
  845. .br
  846. protected:
  847. .OC
  848. .br
  849.    void deepenVBase();
  850. .OC
  851. .br
  852.     void storeVBaseOn(OIOofd&) const;    // store virtual base class
  853. .OC
  854. .br
  855.     void storeVBaseOn(OIOout&) const;
  856. .OC
  857. .br
  858. private:
  859. .OC
  860. .br
  861.     static Object* reader(OIOin& strm);
  862. .OC
  863. .br
  864.     static Object* reader(OIOifd& fd);
  865. 'in 36p
  866. .ad b
  867. 'ft R
  868. .ps 12
  869. .OC
  870. .sp 1
  871. .vs 14
  872. The DECLARE_MEMBERS macro takes a single argument, the name of the class being declared.
  873. .HE
  874. .br
  875. .ad l
  876. 'ft B
  877. .OC
  878. .sp 1
  879. New implementation of Process classes
  880. .ad b
  881. 'ft R
  882. .OC
  883. .sp 1
  884. In R3.0, class \fCProcess\fR has two derived classes, \fCStackProc\fR and \fCHeapProc\fR, which serve 
  885. as the base classes for client processes.  \fCStackProc\fR and \fCHeapProc\fR differ in where a 
  886. process's stack is located when the process is running: a \fCStackProc\fR has its stack located 
  887. on the real stack in the stack segment, while a \fCHeapProc\fR has its stack in the free 
  888. storage area in the data segment.  A context switch of a \fCStackProc\fR involves copying 
  889. the active part of the current process's stack into a save area, then copying the saved 
  890. stack of the new process onto the real stack.  A context switch of a \fCHeapProc\fR involves 
  891. simply resetting the processor's stack pointer and frame pointer registers to point 
  892. to the new stack, so a \fCStackProc\fR context switch is much slower than a \fCHeapProc\fR context 
  893. switch.  However, using \fCHeapProc\fRs tends to break debuggers, which usually can't cope 
  894. with the bizarre stack location, so programs using them are difficult to debug.  Also, 
  895. the stack area for a \fCHeapProc\fR must be specified when it is constructed, and must be 
  896. large enough to hold the largest stack that can occur anytime during execution.  In 
  897. contrast, the stack save area for a \fCStackProc\fR grows in size if necessary and must only 
  898. be large enough to hold the largest stack in use when the process is suspended.  Thus, 
  899. the tradeoff is debuggability and reduced memory requirement vs. speed.
  900. .OC
  901. .sp 1
  902. Fiddling with the stack area and machine registers is something you can't do directly 
  903. from C++, so processes are inherently non-portable.  The R3.0 implementation of the \fC
  904. Process\fR classes attempts to use the C library routines \fCsetjmp()\fR, \fClongjmp()\fR, and \fCalloca()\fR 
  905. to do context switching.  While this works on many machines, you may need to write 
  906. your own versions of these routines for machines on which it doesn't.  See the section 
  907. on \fIPORTING THE PROCESS CLASSES\fR for instructions.
  908. .HE
  909. .br
  910. .ad l
  911. 'ft B
  912. .OC
  913. .sp 1
  914. External \f(CBclass_\f(BIclassname\fB identifiers eliminated
  915. .ad b
  916. 'ft R
  917. .OC
  918. .sp 1
  919. The class descriptor for each class no longer has an external identifier of the form \fC
  920. class_\fIclassname\fR.  Instead, the class descriptor is a static member variable of each 
  921. class, and the inline static member function \fCdesc()\fR returns its address.
  922. .HE
  923. .br
  924. .ad l
  925. 'ft B
  926. .OC
  927. .sp 1
  928. Changes to Object I/O
  929. .ad b
  930. 'ft R
  931. .OC
  932. .sp 1
  933. Previous releases of OOPS have a fundamental problem in the way they handle object 
  934. I/O for classes with member variables that are class instances.  For example, consider 
  935. an OOPS class \fCX\fR with a member variable of class \fCM\fR, where \fCM\fR is also an OOPS class:
  936. 'in 72p
  937. .br
  938. .ad l
  939. 'ft C
  940. .ps 10
  941. .OC
  942. .sp 1
  943. .vs 12
  944. class X : public BASE {
  945. .OC
  946. .br
  947.     M m;    // a member class instance
  948. .OC
  949. .br
  950.     M* p;   // a member pointer to a class instance
  951. .OC
  952. .br
  953.     int i;  // a fundamental type
  954. .OC
  955. .br
  956. // ...
  957. .OC
  958. .br
  959. };
  960. 'in 36p
  961. .ad b
  962. 'ft R
  963. .ps 12
  964. .OC
  965. .sp 1
  966. .vs 14
  967. Previous releases implement \fCX::storer()\fR and\fC X::X(istream&,X&)\fR as follows:
  968. 'in 72p
  969. .br
  970. .ad l
  971. 'ft C
  972. .ps 10
  973. .OC
  974. .sp 1
  975. .vs 12
  976. void X::storer(ostream& strm)
  977. .OC
  978. .br
  979. {
  980. .OC
  981. .br
  982.     BASE::storer(strm);
  983. .OC
  984. .br
  985.     m.storeOn(strm);
  986. .OC
  987. .br
  988.     p->storeOn(strm);
  989. .OC
  990. .br
  991.     strm << i << " ";
  992. .OC
  993. .br
  994. }
  995. .OC
  996. .sp 1
  997. void X::X(istream&strm, X& where)
  998. .OC
  999. .br
  1000.     : (strm,where)
  1001. .OC
  1002. .br
  1003. {
  1004. .OC
  1005. .br
  1006.     this = &where;
  1007. .OC
  1008. .br
  1009.     readFrom(strm,"M",m);
  1010. .OC
  1011. .br
  1012.     p = (M*)readFrom(strm,"M");
  1013. .OC
  1014. .br
  1015.     strm >> i;
  1016. .OC
  1017. .br
  1018. }
  1019. .OC
  1020. .sp 1
  1021. void X::storer(FileDescTy& fd)
  1022. .OC
  1023. .br
  1024. {
  1025. .OC
  1026. .br
  1027.     BASE::storer(fd);
  1028. .OC
  1029. .br
  1030.     m.storeOn(fd);
  1031. .OC
  1032. .br
  1033.     p->storeOn(fd);
  1034. .OC
  1035. .br
  1036.     storeBin(fd,i);
  1037. .OC
  1038. .br
  1039. }
  1040. .OC
  1041. .sp 1
  1042. void X::X(FileDescTy& fd, X& where)
  1043. .OC
  1044. .br
  1045.     : (fd,where)
  1046. .OC
  1047. .br
  1048. {
  1049. .OC
  1050. .br
  1051.     this = &where;
  1052. .OC
  1053. .br
  1054.     readFrom(fd,"M",m);
  1055. .OC
  1056. .br
  1057.     p = (M*)readFrom(fd,"M");
  1058. .OC
  1059. .br
  1060.     readBin(fd,i);
  1061. .OC
  1062. .br
  1063. }
  1064. 'in 36p
  1065. .ad b
  1066. 'ft R
  1067. .ps 12
  1068. .OC
  1069. .sp 1
  1070. .vs 14
  1071. The problem is that this constructor first initializes \fCm\fR using the \fCM::M()\fR constructor, 
  1072. then calls \fCreadFrom()\fR, which overwrites this initialized instance with an instance 
  1073. constructed by reading \fCstrm\fR.  We didn't notice this bug earlier because, in practice, 
  1074. the problem occurs only in classes \fCRectangle\fR and \fCSharedQueue\fR, and has no obvious consequences.  
  1075. The worst that is likely to happen is that \fCM::M()\fR allocates some memory that never 
  1076. gets reclaimed.
  1077. .OC
  1078. .sp 1
  1079. Unfortunately, the fix requires some widespread changes.  But, it turns out that numerous 
  1080. other improvements become possible.  The new format for \fCstorer()\fR functions and \fCreadFrom()\fR 
  1081. constructors when not using MI is:
  1082. 'in 72p
  1083. .br
  1084. .ad l
  1085. 'ft C
  1086. .ps 10
  1087. .OC
  1088. .sp 1
  1089. .vs 12
  1090. void X::storer(OIOout& strm)
  1091. .OC
  1092. .br
  1093. {
  1094. .OC
  1095. .br
  1096.     BASE::storer(strm);
  1097. .OC
  1098. .br
  1099.     m.storeMemberOn(strm);
  1100. .OC
  1101. .br
  1102.     p->storeOn(strm);
  1103. .OC
  1104. .br
  1105.     strm << i;
  1106. .OC
  1107. .br
  1108. }
  1109. .OC
  1110. .sp 1
  1111. void X::X(OIOin& strm)
  1112. .OC
  1113. .br
  1114.     : (strm), m(strm)
  1115. .OC
  1116. .br
  1117. {
  1118. .OC
  1119. .br
  1120.     p = M::readFrom(strm);
  1121. .OC
  1122. .br
  1123.     strm >> i;
  1124. .OC
  1125. .br
  1126. }
  1127. .OC
  1128. .sp 1
  1129. void X::storer(OIOofd& fd)
  1130. .OC
  1131. .br
  1132. {
  1133. .OC
  1134. .br
  1135.     BASE::storer(fd);
  1136. .OC
  1137. .br
  1138.     m.storeMemberOn(fd);
  1139. .OC
  1140. .br
  1141.     p->storeOn(fd);
  1142. .OC
  1143. .br
  1144.     fd << i;
  1145. .OC
  1146. .br
  1147. }
  1148. .OC
  1149. .sp 1
  1150. void X::X(OIOifd& fd)
  1151. .OC
  1152. .br
  1153.     : (fd), m(fd)
  1154. .OC
  1155. .br
  1156. {
  1157. .OC
  1158. .br
  1159.     p = M::readFrom(fd);
  1160. .OC
  1161. .br
  1162.     fd >> i;
  1163. .OC
  1164. .br
  1165. }
  1166. 'in 36p
  1167. .ad b
  1168. 'ft R
  1169. .ps 12
  1170. .OC
  1171. .sp 1
  1172. .vs 14
  1173. The new format is simpler and consistent---\fCstorer()\fR functions always call \fCBASE::storer()\fR 
  1174. and \fCX::X(OIOin&)\fR constructors always call \fCBASE::BASE(OIOin&)\fR.
  1175. .HE
  1176. .br
  1177. .ad l
  1178. 'ft I
  1179. .OC
  1180. .sp 1
  1181. Public \f(COreadFrom()\fI constructor
  1182. .ad b
  1183. 'ft R
  1184. .OC
  1185. .sp 1
  1186. Since other classes in general must have access to \fCX::X(OIOin&)\fR, it must be public 
  1187. instead of protected, requiring a change to all header files.
  1188. .HE
  1189. .br
  1190. .ad l
  1191. 'ft I
  1192. .OC
  1193. .sp 1
  1194. Changes to \f(COreadFrom()
  1195. .ad b
  1196. 'ft R
  1197. .OC
  1198. .sp 1
  1199. As explained previously, calls to \fCreadFrom()\fR that specify the third argument overwrite 
  1200. an initialized instance of a class.  Since this is generally a bad thing to do, the 
  1201. third argument to \fCreadFrom()\fR has been eliminated; thus, \fCreadFrom()\fR will only return 
  1202. a pointer to an object. This form of \fCreadFrom()\fR was used to initialize member class 
  1203. instances.  These must now be initialized via the \fCreadFrom()\fR constructor in the initializer 
  1204. list, as shown in the example.  When converting old programs, these calls to \fCreadFrom()\fR 
  1205. will be flagged as errors because the three argument form of \fCreadFrom()\fR is no longer 
  1206. defined.  \fINote that when you change the \f(COreadFrom()\fI constructor, you must also change 
  1207. the corresponding \f(COstorer()\fI function to store the member using \f(COstoreMemberOn()\fI rather 
  1208. than \f(COstoreOn()\fI.\fR 
  1209. .OC
  1210. .sp 1
  1211. In previous releases, the second argument to \fCreadFrom()\fR was an optional name of the 
  1212. class of object that was expected to be read.  If the object read was of a different 
  1213. class, \fCreadFrom()\fR raised an error.  Beginning with this release, \fCreadFrom(OIOin&)\fR, 
  1214. and \fCreadFrom(OIOifd&)\fR are static member functions of each class which will also accept 
  1215. derived classes of the specified class, just as C++ allows a pointer to a derived class 
  1216. to be used instead of a pointer to a base class.  The global functions \fCreadFrom(istream, 
  1217. const char* classname)\fR and \fCreadFrom(int fd, const char* classname)\fR have been eliminated.
  1218. .br
  1219. .ad l
  1220. 'ft CO
  1221. .OC
  1222. .sp 1
  1223. istream&
  1224. .HE
  1225. 'ft I
  1226. replaced by \f(COOIOin&
  1227. 'ft I
  1228. .ad b
  1229. 'ft R
  1230. .OC
  1231. .sp 1
  1232. The type of the first (and now only) argument to the constructors called by \fCreadFrom(istream&)\fR 
  1233. has been changed from an \fCistream&\fR to an \fCOIOin&\fR.  This avoids naming conflicts with 
  1234. other constructors.  Also, \fCOIOin\fR is an abstract base class, and all input operators 
  1235. are virtual functions, so you can customize the Object I/O format by defining your 
  1236. own derived classes.   \fCOIOistream\fR and \fCOIOnihin\fR implement a format similar to the old 
  1237. OOPS format.
  1238. .br
  1239. .ad l
  1240. 'ft CO
  1241. .OC
  1242. .sp 1
  1243. ostream&
  1244. .HE
  1245. 'ft I
  1246. replaced by \f(COOIOout&
  1247. 'ft I
  1248. .ad b
  1249. 'ft R
  1250. .OC
  1251. .sp 1
  1252. The type of the argument to the \fCstorer(ostream&)\fR function has been changed  to an \fC
  1253. OIOout&\fR.  \fCOIOout\fR is an abstract base class, and all output operators are virtual functions, 
  1254. so you can customize the Object I/O format by defining your own derived classes.   \fC
  1255. OIOostream\fR and \fCOIOnihout\fR implement a format similar to the old OOPS format.
  1256. .HE
  1257. .br
  1258. .ad l
  1259. 'ft I
  1260. .OC
  1261. .sp 1
  1262. Automatic separators output by \f(COOIOostream::operator<<()
  1263. 'ft I
  1264. .ad b
  1265. 'ft R
  1266. .OC
  1267. .sp 1
  1268. It is no longer necessary to explicitly output a space after each number written in 
  1269. a \fCstorer(OIOnihout&)\fR function.  Class \fCOIOostream\fR reimplements \fCoperator<<()\fR to supply 
  1270. the space automatically.
  1271. .br
  1272. .ad l
  1273. 'ft CO
  1274. .OC
  1275. .sp 1
  1276. FileDescTy&
  1277. .HE
  1278. 'ft I
  1279. replaced by \f(COOIOifd&/OIOofd&
  1280. 'ft I
  1281. .ad b
  1282. 'ft R
  1283. .OC
  1284. .sp 1
  1285. The type of the argument to the \fCstorer(FileDescTy&)\fR function has been changed  to 
  1286. an \fCOIOofd&\fR. and the argument to the \fCreadFrom(FileDescTy&)\fR function has been changed 
  1287. to an \fCOIOifd&\fR.  \fCOIOifd\fR and \fCOIOofd\fR are not abstract classes, and their I/O operators 
  1288. are not virtual functions as in \fCOIOin\fR and \fCOIOout\fR, so using them does not incur the 
  1289. overhead of a virtual function call for each member variable.
  1290. .HE
  1291. .br
  1292. .ad l
  1293. 'ft I
  1294. .OC
  1295. .sp 1
  1296. Change to \f(COreadFrom(OIOin&)
  1297. 'ft I
  1298. .ad b
  1299. 'ft R
  1300. .OC
  1301. .sp 1
  1302. Encountering EOF during \fCreadFrom(OIOin&)\fR is now always an error.  Previous releases 
  1303. returned \fCnil\fR if the input stream was initially at the EOF.  \fCreadFrom(OIOin&)\fR now behaves 
  1304. like \fCreadFrom(OIOifd&)\fR always has.
  1305. .br
  1306. .ad l
  1307. 'ft CO
  1308. .OC
  1309. .sp 1
  1310. storeBin()
  1311. .HE
  1312. 'ft I
  1313. replaced by \f(COOIOofd::operator<<()\fI and \f(COOIOofd::put()
  1314. 'ft I
  1315. .ad b
  1316. 'ft R
  1317. .OC
  1318. .sp 1
  1319. The function \fCstoreBin(FileDescTy&, \f(COtype\fC)\fR has been replaced by \fCOIOofd::operator<<(\f(COtype\fC)\fR 
  1320. and the function \fCstoreBin(FileDescTy&, \f(COtype\fC*, unsigned)\fR has been replaced by \fCOIOofd::put(\f(COtype\fC*, 
  1321. unsigned)\fR.
  1322. .br
  1323. .ad l
  1324. 'ft CO
  1325. .OC
  1326. .sp 1
  1327. readBin()
  1328. .HE
  1329. 'ft I
  1330. replaced by \f(COOIOifd::operator>>()\fI and \f(COOIOifd::get()
  1331. 'ft I
  1332. .ad b
  1333. 'ft R
  1334. .OC
  1335. .sp 1
  1336. The function \fCreadBin(FileDescTy&, \f(COtype\fC)\fR has been replaced by \fCOIOifd::operator>>(\f(COtype\fC)\fR 
  1337. and the function \fCreadBin(FileDescTy&, \f(COtype\fC*, unsigned)\fR has been replaced by \fCOIOifd::get(\f(COtype\fC*, 
  1338. unsigned)\fR.
  1339. .br
  1340. .ad l
  1341. 'ft CO
  1342. .OC
  1343. .sp 1
  1344. read_Cstring()
  1345. .HE
  1346. 'ft I
  1347. replaced by \f(COOIOin::getCstring()
  1348. 'ft I
  1349. .ad b
  1350. 'ft R
  1351. .OC
  1352. .sp 1
  1353. The function \fCread_Cstring()\fR has been replaced by \fCOIOin::getCstring()\fR.
  1354. .br
  1355. .ad l
  1356. 'ft CO
  1357. .OC
  1358. .sp 1
  1359. store_Cstring()
  1360. .HE
  1361. 'ft I
  1362. replaced by \f(COOIOout::putCstring()
  1363. 'ft I
  1364. .ad b
  1365. 'ft R
  1366. .OC
  1367. .sp 1
  1368. The function \fCstore_Cstring()\fR has been replaced by \fCOIOout::putCstring()\fR.
  1369. .br
  1370. .ad l
  1371. 'ft CO
  1372. .OC
  1373. .sp 1
  1374. READ_OBJECT_AS_BINARY
  1375. .HE
  1376. 'ft I
  1377. eliminated
  1378. .ad b
  1379. 'ft R
  1380. .OC
  1381. .sp 1
  1382. The \fCREAD_OBJECT_AS_BINARY\fR macro has been eliminated.  Replace it with code to read 
  1383. member variables individually using \fC>>\fR and \fCget()\fR.
  1384. .br
  1385. .ad l
  1386. 'ft CO
  1387. .OC
  1388. .sp 1
  1389. STORE_OBJECT_AS_BINARY
  1390. .HE
  1391. 'ft I
  1392. eliminated
  1393. .ad b
  1394. 'ft R
  1395. .OC
  1396. .sp 1
  1397. The \fCSTORE_OBJECT_AS_BINARY\fR macro has been eliminated.  Replace it with code to store 
  1398. member variables individually using \fC<<\fR and \fCput()\fR.
  1399. .HE
  1400. .br
  1401. .ad l
  1402. 'ft B
  1403. .OC
  1404. .sp 1
  1405. Changes to the \f(CBDEFINE_CLASS\fB macro
  1406. .ad b
  1407. 'ft R
  1408. .OC
  1409. .sp 1
  1410. The new version of the \fCDEFINE_CLASS\fR macro has hooks for supporting multiple inheritance.  
  1411. Before calling the \fCDEFINE_CLASS\fR macro, you must define three preprocessor symbols: \fC
  1412. BASE_CLASSES\fR, \fCMEMBER_CLASSES\fR, and \fCVIRTUAL_BASE_CLASSES\fR.  As an example, suppose you 
  1413. are writing the implementation of a class with the following declaration:
  1414. 'in 72p
  1415. .br
  1416. .ad l
  1417. 'ft C
  1418. .ps 10
  1419. .OC
  1420. .sp 1
  1421. .vs 12
  1422. class X: public A, public virtual B {
  1423. .OC
  1424. .br
  1425.     C c;        // C is a class
  1426. .OC
  1427. .br
  1428.     D d;        // D is a class
  1429. .OC
  1430. .br
  1431. //...
  1432. .OC
  1433. .br
  1434. };
  1435. 'in 36p
  1436. .ad b
  1437. 'ft R
  1438. .ps 12
  1439. .OC
  1440. .sp 1
  1441. .vs 14
  1442. Set the symbol \fCBASE_CLASSES\fR to a list of the addresses of the class descriptors for 
  1443. the base classes of the class you are defining.  These must be in the same order as 
  1444. they appear in the class declaration:
  1445. 'in 72p
  1446. .br
  1447. .ad l
  1448. 'ft C
  1449. .ps 10
  1450. .OC
  1451. .sp 1
  1452. .vs 12
  1453. #define BASE_CLASSES A::desc(), B::desc()
  1454. 'in 36p
  1455. .ad b
  1456. 'ft R
  1457. .ps 12
  1458. .OC
  1459. .sp 1
  1460. .vs 14
  1461. Set the symbol \fCMEMBER_CLASSES\fR to a list of the addresses of the class descriptors 
  1462. for any member variables of the class that are NIH Library classes.  These must be 
  1463. in the same order as they appear in the class declaration:
  1464. 'in 72p
  1465. .br
  1466. .ad l
  1467. 'ft C
  1468. .ps 10
  1469. .OC
  1470. .sp 1
  1471. .vs 12
  1472. #define MEMBER_CLASSES C::desc(), D::desc()
  1473. 'in 36p
  1474. .ad b
  1475. 'ft R
  1476. .ps 12
  1477. .OC
  1478. .sp 1
  1479. .vs 14
  1480. If a class has no class members, define \fCMEMBER_CLASSES\fR, but give it no value.
  1481. .OC
  1482. .sp 1
  1483. Set the symbol \fCVIRTUAL_BASE_CLASSES\fR to a list of the addresses of the class descriptors 
  1484. for the virtual base classes of the class you are defining.  These must be in the same 
  1485. order as they appear in the class declaration:
  1486. 'in 72p
  1487. .br
  1488. .ad l
  1489. 'ft C
  1490. .ps 10
  1491. .OC
  1492. .sp 1
  1493. .vs 12
  1494. #define VIRTUAL_BASE_CLASSES B::desc()
  1495. 'in 36p
  1496. .ad b
  1497. 'ft R
  1498. .ps 12
  1499. .OC
  1500. .sp 1
  1501. .vs 14
  1502. If a class has no virtual base classes, define \fCVIRTUAL_BASE_CLASSES\fR, but give it no 
  1503. value.
  1504. .OC
  1505. .sp 1
  1506. Now you are ready to call the \fCDEFINE_CLASS\fR macro:
  1507. 'in 72p
  1508. .br
  1509. .ad l
  1510. 'ft C
  1511. .ps 10
  1512. .OC
  1513. .sp 1
  1514. .vs 12
  1515. DEFINE_CLASS(\f(COclassname\fC,\f(COversion\fC,\f(COidentification\fC,\f(COinitor1\fC,\f(COinitor2\fC)
  1516. 'in 36p
  1517. .ad b
  1518. 'ft R
  1519. .ps 12
  1520. 'ft I
  1521. .OC
  1522. .sp 1
  1523. .vs 14
  1524. Classname\fR is the name of the class you are defining.\fI
  1525. .OC
  1526. .sp 1
  1527. Version\fR is the version number of the class you are defining.  It should be changed 
  1528. whenever the format of the information written by the \fCstorer()\fR function changes such 
  1529. that older versions of \fCreadFrom()\fR can no longer interpret it correctly.\fI
  1530. .OC
  1531. .sp 1
  1532. Identification\fR is a character string that identifies the revision level of the implementation 
  1533. of the class.  It is simply stored in the class descriptor where you can retrieve it 
  1534. by calling the function \fCClass::ident()\fR.  The identification parameter is intended for 
  1535. use with a revision control system such as RCS or SCCS.  NIH Library classes specify 
  1536. it as the string "\fC$Header$\fR", which RCS replaces with the revision identification.\fI
  1537. .OC
  1538. .sp 1
  1539. Initor1\fR and \fIinitor2\fR are pointers to functions you may supply to perform initialization 
  1540. for the class, for example, initializing \fCstatic\fR data that the class uses.
  1541. .HE
  1542. .br
  1543. .ad l
  1544. 'ft CB
  1545. .OC
  1546. .sp 1
  1547. DEFINE_ABSTRACT_CLASS
  1548. .ad b
  1549. 'ft R
  1550. .OC
  1551. .sp 1
  1552. Abstract classes should use the new macro \fCDEFINE_ABSTRACT_CLASS\fR instead of \fCDEFINE_CLASS\fR.  \fC
  1553. DEFINE_ABSTRACT_CLASS \fRhas the same arguments as \fCDEFINE_CLASS\fR; the only difference is 
  1554. that the \fCreader()\fR functions it generates do not reference the class's object I/O constructors, 
  1555. and \fCshallowCopy()\fR is defined as a \fCderivedClassResponsibility()\fR.
  1556. .HE
  1557. .br
  1558. .ad l
  1559. 'ft B
  1560. .OC
  1561. .sp 1
  1562. Change to \f(CBClass::className()
  1563. 'ft B
  1564. .ad b
  1565. 'ft R
  1566. .OC
  1567. .sp 1
  1568. The function \fCclassName()\fR returns the name of the class of the object to which it is 
  1569. applied.  In previous releases \fCClass::className()\fR does not do this.  Instead, it returns 
  1570. the name of the class described by the class object to which it is applied.  This release 
  1571. eliminates this inconsistency: \fCclassName()\fR returns \fC"Class"\fR when applied to an instance 
  1572. of class \fCClass\fR.  The new function \fCClass::name()\fR returns the name of the class described 
  1573. by an instance of class \fCClass\fR.
  1574. .HE
  1575. .br
  1576. .ad l
  1577. 'ft B
  1578. .OC
  1579. .sp 1
  1580. New member functions of class \f(CBClass
  1581. 'ft B
  1582. .ad b
  1583. 'ft R
  1584. 'ft C
  1585. .OC
  1586. .sp 1
  1587. Class** baseClasses()\fR returns a zero-terminated array of pointers to the class descriptors 
  1588. of the base classes of this class.\fC
  1589. .OC
  1590. .sp 1
  1591. Class** memberClasses()\fR returns a zero-terminated array of pointers to the class descriptors 
  1592. of the member classes of this class.\fC
  1593. .OC
  1594. .sp 1
  1595. Class** virtualBaseClasses()\fR returns a zero-terminated array of pointers to the class 
  1596. descriptors of the virtual base classes of this class.\fC
  1597. .OC
  1598. .sp 1
  1599. unsigned long signature()\fR returns the signature of this class.  The signature of a 
  1600. class is computed by hashing the signatures of this class's base and member classes 
  1601. and the version number of this class.  It is currently used by \fCstoreOn()\fR/\fCreadFrom()\fR 
  1602. to prevent obsolete versions of objects from being read.\fC
  1603. .OC
  1604. .sp 1
  1605. const Class* Class::lookup(const char* name)\fR returns a pointer to the class descriptor 
  1606. object for the class with the specified name.  \fCClass::lookup()\fR returns 0 if the name 
  1607. is not found.
  1608. .HE
  1609. .br
  1610. .ad l
  1611. 'ft B
  1612. .OC
  1613. .sp 1
  1614. Changes to \f(CBcopy()\fB, \f(CBshallowCopy()\fB, and \f(CBdeepCopy()
  1615. 'ft B
  1616. .ad b
  1617. 'ft R
  1618. .OC
  1619. .sp 1
  1620. In previous releases, \fCshallowCopy()\fR made a bitwise copy of an object, and \fCdeepCopy()\fR 
  1621. first made a shallow copy of an object, and then called the virtual function \fCdeepenShallowCopy()\fR 
  1622. to convert the shallow copy to a deep copy.  Each class reimplemented \fCdeepenShallowCopy()\fR 
  1623. to handle any pointer member variables contained in instances of its class.
  1624. .OC
  1625. .sp 1
  1626. The problems with this approach are that (1) it is usually unsafe to make a shallow 
  1627. copy of an object that contains pointers, and (2) with Release 2.0 of the AT&T C++ 
  1628. Translator, objects may contain compiler-generated pointers which \fCdeepenShallowCopy()\fR 
  1629. cannot handle easily and portably.
  1630. .OC
  1631. .sp 1
  1632. The following changes have been made in an attempt to solve these problems:
  1633. .OC
  1634. .sp 1
  1635. Each class now reimplements the virtual function \fCshallowCopy()\fR to call the initialization 
  1636. constructor \fCX::X(const X&)\fR to make a shallow copy of an object.  The implementation 
  1637. of \fCshallowCopy()\fR is the same for all classes and is generated automatically by the \fC
  1638. DEFINE_CLASS\fR macro:
  1639. 'in 72p
  1640. .br
  1641. .ad l
  1642. 'ft C
  1643. .ps 10
  1644. .OC
  1645. .sp 1
  1646. .vs 12
  1647. Object* \f(COclassname\fC::shallowCopy()
  1648. .OC
  1649. .br
  1650. {
  1651. .OC
  1652. .br
  1653.     return new \f(COclassname\fC(*this);
  1654. .OC
  1655. .br
  1656. }
  1657. 'in 36p
  1658. .ad b
  1659. 'ft R
  1660. .ps 12
  1661. 'ft C
  1662. .OC
  1663. .sp 1
  1664. .vs 14
  1665. Object::deepCopy()\fR still calls the virtual function \fCdeepenShallowCopy()\fR to convert 
  1666. a shallow copy, now made by the initialization constructor, to a deep copy.  Since 
  1667. the shallow copy is no longer a simple bitwise copy, you may need to change \fCdeepenShallowCopy()\fR 
  1668. for some classes.
  1669. .OC
  1670. .sp 1
  1671. In previous releases, \fCcopy()\fR defaulted to \fCdeepCopy()\fR since it was unsafe for general 
  1672. use.  Beginning with this release, \fCcopy()\fR defaults to \fCshallowCopy()\fR as it does in Smalltalk-80.  
  1673. Also, \fCObject::deepCopy()\fR is no longer a virtual function.
  1674. .HE
  1675. .br
  1676. .ad l
  1677. 'ft B
  1678. .OC
  1679. .sp 1
  1680. New function \f(CBdumpOn()\fB and changes to \f(CBprintOn()
  1681. 'ft B
  1682. .ad b
  1683. 'ft R
  1684. .OC
  1685. .sp 1
  1686. To make the \fCprintOn()\fR function more useful in application programs, it has been changed 
  1687. to print minimal formatting information, the idea being that this can frequently be 
  1688. added by an application to suit its specific needs.  The virtual function \fCdumpOn()\fR 
  1689. has been added to assist in debugging by printing more detailed information than \fCprintOn()\fR.  \fC
  1690. Object::dumpOn()\fR prints the name of an object's class, a left square bracket (\fC"["\fR), 
  1691. calls \fCprintOn()\fR, then prints a matching right square bracket and a newline (\fC"]\\n"\fR).  \fC
  1692. Collection::dumpOn()\fR does the same, except that it applies \fCdumpOn()\fR to all objects 
  1693. in the collection instead of calling \fCprintOn()\fR.  Other classes reimplement \fCdumpOn()\fR 
  1694. to print more appropriate information.
  1695. .OC
  1696. .sp 1
  1697. By default, \fCdumpOn()\fR sends its output to \fCcerr\fR.  A default argument has also been added 
  1698. to \fCprintOn()\fR so that it writes to \fCcout\fR by default.
  1699. .HE
  1700. .br
  1701. .ad l
  1702. 'ft B
  1703. .OC
  1704. .sp 1
  1705. Changes to class \f(CBLink
  1706. 'ft B
  1707. .ad b
  1708. 'ft R
  1709. .HE
  1710. .br
  1711. .ad l
  1712. 'ft I
  1713. .OC
  1714. .sp 1
  1715. Constructor \f(COLink(const Link&)\fI changed to \f(COLink(Link*)
  1716. .ad b
  1717. 'ft R
  1718. .OC
  1719. .sp 1
  1720. The constructor \fCLink(const Link&)\fR, which constructs a \fCLink\fR that points to the argument \fC
  1721. Link\fR, has been replaced by the constructor \fCLink(Link*)\fR.  This change was necessary 
  1722. so that \fCshallowCopy()\fR could call the constructor \fCLink(const Link&)\fR to make a bitwise 
  1723. copy.  We suggest temporarily commenting out the declaration of this constructor in 
  1724. the file \fCLink.h\fR and recompiling the programs that depend upon it so you can easily 
  1725. detect and change the code using \fCLink(const Link&)\fR to use the new \fCLink(Link*)\fR constructor 
  1726. instead.
  1727. .OC
  1728. .sp 1
  1729. As a result of this change, \fCLink::shallowCopy()\fR is now enabled and will return a bitwise 
  1730. copy of a \fCLink\fR.
  1731. .HE
  1732. .br
  1733. .ad l
  1734. 'ft I
  1735. .OC
  1736. .sp 1
  1737. New function \f(COisListEnd()
  1738. .ad b
  1739. 'ft R
  1740. .OC
  1741. .sp 1
  1742. Class \fCLink\fR has a new member function \fCbool isListEnd()\fR, which you must use to check 
  1743. for the end of a \fCLinkedList\fR instead of checking for a pointer to \fCNil\fR.  Compile your 
  1744. program with \fC-DMI\fR to find the places where you need to make this change.
  1745. .HE
  1746. .br
  1747. .ad l
  1748. 'ft B
  1749. .OC
  1750. .sp 1
  1751. Changes to class \f(CBIterator
  1752. 'ft B
  1753. .ad b
  1754. 'ft R
  1755. 'ft C
  1756. .OC
  1757. .sp 1
  1758. Iterator::shallowCopy()\fR now produces a shallow copy with a pointer to the same collection 
  1759. bound to the original instead of to a shallow copy of the collection bound to the original, 
  1760. as in prior releases.  \fCIterator::deepCopy()\fR works as before: it produces a deep copy 
  1761. with a pointer to a deep copy of the collection bound to the original.
  1762. .OC
  1763. .sp 1
  1764. The member variable \fCObject* state\fR has been added, which collection classes can use 
  1765. to associate additional state information with an \fCIterator\fR.  For example, a collection 
  1766. class implemented as a tree structure can use \fCstate\fR to point to a \fCStack\fR used to maintain 
  1767. the state of a traversal of the tree.  The destructor for class \fCIterator\fR calls a new 
  1768. virtual function, \fCdoFinish()\fR, which a class that uses \fCstate\fR can reimplement to delete 
  1769. the state object when the \fCIterator\fR is destroyed.
  1770. .OC
  1771. .sp 1
  1772. The \fCstoreOn()\fR format has changed as a result of these modifications.
  1773. .OC
  1774. .sp 1
  1775. The function \fCObject* Iterator::operator()()\fR has been added to return a pointer to 
  1776. the current object, or 0 if there is none.
  1777. .HE
  1778. .br
  1779. .ad l
  1780. 'ft B
  1781. .OC
  1782. .sp 1
  1783. Changes to class \f(CBDictionary
  1784. 'ft B
  1785. .ad b
  1786. 'ft R
  1787. .OC
  1788. .sp 1
  1789. The return type of \fCassocAt()\fR, \fCremoveAssoc()\fR, and \fCremoveKey()\fR has been changed from \fC
  1790. LookupKey&\fR to \fCLookupKey*\fR for consistency with the return types of similar functions.  \fC
  1791. Dictionary::assocAt()\fR returns 0 instead of \fCnil\fR if the key is not found.
  1792. .br
  1793. .ad l
  1794. 'ft CB
  1795. .OC
  1796. .sp 1
  1797. const
  1798. .HE
  1799. 'ft B
  1800. arguments to member functions
  1801. .ad b
  1802. 'ft R
  1803. .OC
  1804. .sp 1
  1805. In previous versions , it was possible to convert, or "widen", a pointer to a \fCconst\fR 
  1806. object into a pointer to a non-\fCconst\fR object by adding the \fCconst\fR object to a collection 
  1807. class and then removing it:
  1808. 'in 72p
  1809. .br
  1810. .ad l
  1811. 'ft C
  1812. .ps 10
  1813. .OC
  1814. .sp 1
  1815. .vs 12
  1816. Object* f(const Object& co)
  1817. .OC
  1818. .br
  1819. {
  1820. .OC
  1821. .br
  1822.     OrderedCltn c;
  1823. .OC
  1824. .br
  1825.     c.add(co);
  1826. .OC
  1827. .br
  1828.     return c.remove(co);
  1829. .OC
  1830. .br
  1831. }
  1832. 'in 36p
  1833. .ad b
  1834. 'ft R
  1835. .ps 12
  1836. .OC
  1837. .sp 1
  1838. .vs 14
  1839. C++ R2.0 now issues error or warning messages when a \fCconst\fR pointer is converted into 
  1840. a non-\fCconst\fR pointer.  To eliminate these problems, the const arguments to some functions 
  1841. such as \fCadd()\fR have been changed to non-\fCconst\fR arguments.  These changes affect classes \fC
  1842. Assoc\fR, \fCLinkOb\fR, and the collection classes.
  1843. .OC
  1844. .sp 1
  1845. If you need to add a \fCconst\fR object to a collection class, you must use an explicit 
  1846. cast:
  1847. 'in 72p
  1848. .br
  1849. .ad l
  1850. 'ft C
  1851. .ps 10
  1852. .OC
  1853. .sp 1
  1854. .vs 12
  1855. c.add((Object&)co);
  1856. 'in 36p
  1857. .ad b
  1858. 'ft R
  1859. .ps 12
  1860. .HE
  1861. .br
  1862. .ad l
  1863. 'ft B
  1864. .OC
  1865. .sp 1
  1866. .vs 14
  1867. Change to \f(CBBag::remove(const Object&)
  1868. 'ft B
  1869. .ad b
  1870. 'ft R
  1871. 'ft C
  1872. .OC
  1873. .sp 1
  1874. Bag::remove(const Object&)\fR now returns 0 until last occurrence removed instead of 
  1875. the address of the argument to eliminate "widening" of the \fCconst\fR argument.
  1876. .br
  1877. .ad l
  1878. 'ft CB
  1879. .OC
  1880. .sp 1
  1881. shouldNotImplement()
  1882. .HE
  1883. 'ft B
  1884. functions now \f(CBprivate
  1885. 'ft B
  1886. .ad b
  1887. 'ft R
  1888. .OC
  1889. .sp 1
  1890. Virtual member functions that a class reimplements to call \fCshouldNotImplement()\fR have 
  1891. been made private so that the compiler can give an error message if a client program 
  1892. attempts to apply the function to an instance of the class.
  1893. .HE
  1894. .br
  1895. .ad l
  1896. 'ft B
  1897. .OC
  1898. .sp 1
  1899. Change to class Stack
  1900. .ad b
  1901. 'ft R
  1902. .OC
  1903. .sp 1
  1904. When a \fCStack\fR is converted to another type of collection, the objects in the \fCStack\fR 
  1905. are added to the collection from the top of the stack down.  Previous releases added 
  1906. them bottom-up.
  1907. .HE
  1908. .br
  1909. .ad l
  1910. 'ft B
  1911. .OC
  1912. .sp 1
  1913. Changes to class Heap
  1914. .ad b
  1915. 'ft R
  1916. .OC
  1917. .sp 1
  1918. The new member function \fCHeap::removeId(const Object&)\fR allows you to remove the object 
  1919. that is the \fIsame\fR (i.e. \fCisSame()\fR) as the argument object from a \fCHeap\fR.
  1920. .OC
  1921. .sp 1
  1922. Iterating over a \fCHeap\fR now visits the objects in the heap in sorted order, from smallest 
  1923. to largest.  Previous implementations visited the objects in heap order.  This affects 
  1924. the order in which \fCprintOn()\fR lists the objects in a \fCHeap\fR, for example.
  1925. .HE
  1926. .br
  1927. .ad l
  1928. 'ft B
  1929. .OC
  1930. .sp 1
  1931. Changes to class LinkedList
  1932. .ad b
  1933. 'ft R
  1934. .OC
  1935. .sp 1
  1936. The new member function \fCLinkedList::removeId(const Object&)\fR allows you to remove the 
  1937. object that is the \fIsame\fR (i.e. \fCisSame()\fR) as the argument object from a \fCLinkedList\fR.
  1938. .HE
  1939. .br
  1940. .ad l
  1941. 'ft B
  1942. .OC
  1943. .sp 1
  1944. Changes to class LookupKey
  1945. .ad b
  1946. 'ft R
  1947. .OC
  1948. .sp 1
  1949. The virtual function \fCObject* LookupKey::value() const\fR has been replaced by two virtual 
  1950. functions
  1951. 'in 72p
  1952. .br
  1953. .ad l
  1954. 'ft C
  1955. .ps 10
  1956. .OC
  1957. .sp 1
  1958. .vs 12
  1959. virtual Object* value();
  1960. .OC
  1961. .br
  1962. virtual const Object* value() const;
  1963. 'in 36p
  1964. .ad b
  1965. 'ft R
  1966. .ps 12
  1967. .OC
  1968. .sp 1
  1969. .vs 14
  1970. to prevent obtaining a non-const pointer from a const \fCLookupKey\fR.
  1971. .HE
  1972. .br
  1973. .ad l
  1974. 'ft B
  1975. .OC
  1976. .sp 1
  1977. Changes to class Arraychar
  1978. .ad b
  1979. 'ft R
  1980. .OC
  1981. .sp 1
  1982. The constructor for class \fCArraychar\fR now initializes each element of the the array 
  1983. to 0.
  1984. .OC
  1985. .sp 1
  1986. The virtual function \fCremoveAll()\fR has been implemented, which resets each element of 
  1987. the array to 0.
  1988. .HE
  1989. .br
  1990. .ad l
  1991. 'ft B
  1992. .OC
  1993. .sp 1
  1994. Changes to class Assoc
  1995. .ad b
  1996. 'ft R
  1997. .OC
  1998. .sp 1
  1999. The virtual function \fCObject* Assoc::value() const\fR has been replaced by two virtual 
  2000. functions
  2001. 'in 72p
  2002. .br
  2003. .ad l
  2004. 'ft C
  2005. .ps 10
  2006. .OC
  2007. .sp 1
  2008. .vs 12
  2009. virtual Object* value();
  2010. .OC
  2011. .br
  2012. virtual const Object* value() const;
  2013. 'in 36p
  2014. .ad b
  2015. 'ft R
  2016. .ps 12
  2017. .OC
  2018. .sp 1
  2019. .vs 14
  2020. to prevent obtaining a non-const pointer from a const \fCAssoc\fR.
  2021. .HE
  2022. .br
  2023. .ad l
  2024. 'ft B
  2025. .OC
  2026. .sp 1
  2027. Changes to class AssocInt
  2028. .ad b
  2029. 'ft R
  2030. .OC
  2031. .sp 1
  2032. The virtual function \fCObject* AssocInt::value() const\fR has been replaced by two virtual 
  2033. functions
  2034. 'in 72p
  2035. .br
  2036. .ad l
  2037. 'ft C
  2038. .ps 10
  2039. .OC
  2040. .sp 1
  2041. .vs 12
  2042. virtual Object* value();
  2043. .OC
  2044. .br
  2045. virtual const Object* value() const;
  2046. 'in 36p
  2047. .ad b
  2048. 'ft R
  2049. .ps 12
  2050. .OC
  2051. .sp 1
  2052. .vs 14
  2053. to prevent obtaining a non-const pointer from a const \fCAssocInt\fR.
  2054. .HE
  2055. .br
  2056. .ad l
  2057. 'ft B
  2058. .ps 14
  2059. .OC
  2060. .sp 2
  2061. .vs 16
  2062. CHANGES BETWEEN OOPS V2R1 AND OOPS V2R2
  2063. .ad b
  2064. 'ft R
  2065. .ps 12
  2066. .HE
  2067. .br
  2068. .ad l
  2069. 'ft B
  2070. .OC
  2071. .sp 1
  2072. .vs 14
  2073. Class name changes
  2074. .ad b
  2075. 'ft R
  2076. .OC
  2077. .sp 1
  2078. The name of class \fCArrayobid\fR is now \fCArrayOb\fR, the name of class \fCLinkobid\fR is now \fCLinkOb\fR, 
  2079. and the typedef \fCobid\fR has been removed.  Just change all occurrences of \fCArrayobid\fR to \fC
  2080. ArrayOb\fR, \fCLinkobid\fR to \fCLinkOb\fR, and \fCobid\fR to \fCObject*\fR.
  2081. .HE
  2082. .br
  2083. .ad l
  2084. 'ft B
  2085. .OC
  2086. .sp 1
  2087. Type \f(CBbool\fB now \f(CBint
  2088. 'ft B
  2089. .ad b
  2090. 'ft R
  2091. .OC
  2092. .sp 1
  2093. Type \fCbool\fR has been changed from \fCchar\fR to \fCint\fR for compatibility with X V11.
  2094. .HE
  2095. .br
  2096. .ad l
  2097. 'ft B
  2098. .OC
  2099. .sp 1
  2100. New \f(CBString\fB class
  2101. .ad b
  2102. 'ft R
  2103. .OC
  2104. .sp 1
  2105. There is a new, more efficient implementation of class \fCString\fR.  The new \fCString\fR class 
  2106. is compatible with the old \fCString\fR class except for the following:
  2107. 'in 72p
  2108. .br
  2109. .ad l
  2110. 'ft C
  2111. .ps 10
  2112. .OC
  2113. .sp 1
  2114. .vs 12
  2115. String(char c, unsigned l =1);
  2116. 'in 36p
  2117. .ad b
  2118. 'ft R
  2119. .ps 12
  2120. .OC
  2121. .sp 1
  2122. .vs 14
  2123. is now:
  2124. 'in 72p
  2125. .br
  2126. .ad l
  2127. 'ft C
  2128. .ps 10
  2129. .OC
  2130. .sp 1
  2131. .vs 12
  2132. String(char& c, unsigned l=1,
  2133. .OC
  2134. .br
  2135.     unsigned extra=DEFAULT_STRING_EXTRA);
  2136. 'in 36p
  2137. .ad b
  2138. 'ft R
  2139. .ps 12
  2140. .OC
  2141. .sp 1
  2142. .vs 14
  2143. The argument\fC unsigned extra\fR has been added to most of the \fCString::String()\fR constructors 
  2144. to allow the programmer to give a hint as to how much space to allocate in the string 
  2145. for additional characters.  When properly used, this can reduce the number of calls 
  2146. made to the memory allocator.
  2147. .OC
  2148. .sp 1
  2149. Assignment to substrings has changed slightly.  The old \fCString\fR class handled an assignment 
  2150. to a substring such as:
  2151. 'in 72p
  2152. .br
  2153. .ad l
  2154. 'ft C
  2155. .ps 10
  2156. .OC
  2157. .sp 1
  2158. .vs 12
  2159. String s = "abcdef";
  2160. .OC
  2161. .br
  2162. s(0,2) = "123";         // result is 12cdef
  2163. 'in 36p
  2164. .ad b
  2165. 'ft R
  2166. .ps 12
  2167. .OC
  2168. .sp 1
  2169. .vs 14
  2170. by truncating the source string to the length of the destination substring.  An assignment 
  2171. such as:
  2172. 'in 72p
  2173. .br
  2174. .ad l
  2175. 'ft C
  2176. .ps 10
  2177. .OC
  2178. .sp 1
  2179. .vs 12
  2180. s(0,2) = "1";           // result is 1\\0cdef
  2181. 'in 36p
  2182. .ad b
  2183. 'ft R
  2184. .ps 12
  2185. .OC
  2186. .sp 1
  2187. .vs 14
  2188. would cause a null byte to be inserted in the destination substring.
  2189. .OC
  2190. .sp 1
  2191. The new \fCString\fR class replaces the target substring with the source string, adjusting 
  2192. the length of the target string if necessary.  Thus
  2193. 'in 72p
  2194. .br
  2195. .ad l
  2196. 'ft C
  2197. .ps 10
  2198. .OC
  2199. .sp 1
  2200. .vs 12
  2201. String s = "abcdef";
  2202. .OC
  2203. .br
  2204. s(0,2) = "123";         // result is 123cdef
  2205. 'in 36p
  2206. .ad b
  2207. 'ft R
  2208. .ps 12
  2209. .OC
  2210. .sp 1
  2211. .vs 14
  2212. and:    
  2213. 'in 72p
  2214. .br
  2215. .ad l
  2216. 'ft C
  2217. .ps 10
  2218. .OC
  2219. .sp 1
  2220. .vs 12
  2221. s(0,2) = "1";           // result is 1cdef
  2222. 'in 36p
  2223. .ad b
  2224. 'ft R
  2225. .ps 12
  2226. .HE
  2227. .br
  2228. .ad l
  2229. 'ft B
  2230. .OC
  2231. .sp 1
  2232. .vs 14
  2233. Changes to Class \f(CBProcess
  2234. 'ft B
  2235. .ad b
  2236. 'ft R
  2237. .OC
  2238. .sp 1
  2239. An interface to \fCselect\fR(2) has been added:
  2240. 'in 72p
  2241. .br
  2242. .ad l
  2243. 'ft C
  2244. .ps 10
  2245. .OC
  2246. .sp 1
  2247. .vs 12
  2248. void Process::select(FDSet& rdmask, FDSet& wrmask, FDSet& exmask);
  2249. 'in 36p
  2250. .ad b
  2251. 'ft R
  2252. .ps 12
  2253. .HE
  2254. .br
  2255. .ad l
  2256. 'ft B
  2257. .ps 14
  2258. .OC
  2259. .sp 2
  2260. .vs 16
  2261. PORTING THE PROCESS CLASSES
  2262. .ad b
  2263. 'ft R
  2264. .ps 12
  2265. .OC
  2266. .sp 1
  2267. .vs 14
  2268. This section describes the steps to follow if you want to be a pioneer and port the \fC
  2269. Process\fR classes to a new machine/operating system.
  2270. .OC
  2271. .sp 1
  2272. If your target system provides the C library routines \fCsetjmp()\fR, \fClongjmp()\fR, and \fCalloca()\fR, 
  2273. and if the implementation of \fCsetjmp()\fR/\fClongjmp()\fR operates by saving/restoring all of 
  2274. the machine's volatile registers (as they do on the Sun-3, Sun-4, and IBM RT/AOS), 
  2275. then the port should be very easy; otherwise, you'll need to write versions of these 
  2276. routines in assembly language that behave as expected.
  2277. .OC
  2278. .sp 1
  2279. To find out how your \fCsetjmp()\fR/\fClongjmp()\fR works, either look at the source code for 
  2280. these routines (if you're fortunate enough to have it) or use the debugger to disassemble 
  2281. them.  A data structure of type \fCjmp_buf\fR, defined in \fCsetjmp.h\fR, is passed as an argument 
  2282. to these routines.  If your \fCsetjmp()\fR just saves all the volatile registers in it to 
  2283. be restored later by \fClongjmp()\fR, then you're probably in luck---all you need to figure 
  2284. out are the offsets in the \fCjmp_buf\fR structure where the PC (Program Counter), SP (Stack 
  2285. Pointer), and FP (Frame Pointer) registers are saved.
  2286. .OC
  2287. .sp 1
  2288. Next, look at \fCnihclconfig.h\fR and locate the place where it defines the machine-specific 
  2289. inline functions \fCSETJMP()\fR, \fCLONGJMP()\fR, \fC_SETJMP()\fR, \fC_LONGJMP()\fR, \fCENV_PC()\fR, \fCENV_SP()\fR, and \fC
  2290. ENV_FP()\fR.  These define the interface to the \fCProcess\fR classes.  For example, here are 
  2291. the definitions for SunOS 4.0 on the Sun-3:
  2292. 'in 72p
  2293. .br
  2294. .ad l
  2295. 'ft C
  2296. .ps 10
  2297. .OC
  2298. .sp 1
  2299. .vs 12
  2300. #ifdef SUNOS4
  2301. .OC
  2302. .sp 1
  2303. #ifdef mc68000
  2304. .OC
  2305. .br
  2306. typedef jmp_buf JMP_BUF;
  2307. .OC
  2308. .br
  2309. inline int SETJMP(JMP_BUF env)              { return setjmp(env); }
  2310. .OC
  2311. .br
  2312. inline void LONGJMP(JMP_BUF env, int val)   { longjmp(env,val); }
  2313. .OC
  2314. .br
  2315. inline int _SETJMP(JMP_BUF env)             { return _setjmp(env); }
  2316. .OC
  2317. .br
  2318. inline void _LONGJMP(JMP_BUF env, int val)  { _longjmp(env,val); }
  2319. .OC
  2320. .br
  2321. inline unsigned& ENV_PC(JMP_BUF env)        
  2322. .OC
  2323. .br
  2324.                     { return (unsigned&)env[3]; }
  2325. .OC
  2326. .br
  2327. inline unsigned& ENV_SP(JMP_BUF env)        
  2328. .OC
  2329. .br
  2330.                     { return (unsigned&)env[2]; }
  2331. .OC
  2332. .br
  2333. inline unsigned& ENV_FP(JMP_BUF env)        
  2334. .OC
  2335. .br
  2336.                     { return (unsigned&)env[15]; }
  2337. .OC
  2338. .br
  2339. #endif
  2340. .OC
  2341. .sp 1
  2342. // ...
  2343. .OC
  2344. .br
  2345. #endif
  2346. 'in 36p
  2347. .ad b
  2348. 'ft R
  2349. .ps 12
  2350. .OC
  2351. .sp 1
  2352. .vs 14
  2353. Add an \fC#if\fR ... \fC#endif\fR section for your machine and define the \fCENV_PC()\fR, \fCENV_SP()\fR, 
  2354. and \fCENV_FP()\fR functions to return a reference to the appropriate word in the \fCJMP_BUF\fR 
  2355. array.
  2356. .OC
  2357. .sp 1
  2358. If your machine doesn't use both an SP and FP, then you'll also need to add some machine 
  2359. dependent C++ code to \fCHeapProc.c\fR to relocate only the one actually used.  See the code 
  2360. for the \fCibm032\fR in \fCHeapProc.c\fR as an example.
  2361. .OC
  2362. .sp 1
  2363. If your system has both \fCsetjmp()\fR/\fClongjmp()\fR and \fC_setjmp()\fR/\fC_longjmp()\fR, define \fCSETJMP()\fR, \fC
  2364. LONGJMP()\fR, \fC_SETJMP()\fR, and \fC_LONGJMP()\fR to call the corresponding routine.  If your system 
  2365. doesn't have the "\fC_\fR" versions, check your documentation to see if your \fCsetjmp()\fR/\fClongjmp()\fR 
  2366. saves and restores the signal mask; if so, define \fC_SETJMP()\fR and \fC_LONGJMP()\fR to call \fC
  2367. setjmp()\fR and \fClongjmp()\fR, respectively.  See the code for \fCSUNOS3\fR as an example.
  2368. .OC
  2369. .sp 1
  2370. If your \fCsetjmp()\fR and \fClongjmp()\fR do \fInot\fR save and restore the signal mask, you'll need 
  2371. to provide versions that do.  Define \fCJMP_BUF\fR to be a struct that consists of a \fCjmp_buf\fR 
  2372. plus whatever other members you need to save the signal mask.  Then define \fC_SETJMP()\fR 
  2373. and \fC_LONGJMP()\fR to call \fCsetjmp()\fR and \fClongjmp()\fR using the \fCjmp_buf\fR part of a \fCJMP_BUF\fR, 
  2374. and define \fCSETJMP()\fR and \fCLONGJMP()\fR to do the same, but in addition to save/restore the 
  2375. signal mask using the other members of a \fCJMP_BUF\fR.  See the code for the \fCmc300\fR as an 
  2376. example.
  2377. .OC
  2378. .sp 1
  2379. If your \fCsetjmp()\fR/\fClongjmp()\fR do not work by saving/restoring all volatile registers 
  2380. (as on the VAX), you'll need to write versions with different names that do, and call 
  2381. these instead from the interface functions.
  2382. .OC
  2383. .sp 1
  2384. If you succeed in porting the \fCProcess\fR classes to a new machine/operating system, we'd 
  2385. appreciate a copy of the code for inclusion in future releases.
  2386. .HE
  2387. .br
  2388. .ad l
  2389. 'ft B
  2390. .ps 14
  2391. .OC
  2392. .sp 2
  2393. .vs 16
  2394. AT&T C++ TRANSLATOR RELEASE 2.00/2.1 BUGS
  2395. .ad b
  2396. 'ft R
  2397. .ps 12
  2398. .OC
  2399. .sp 1
  2400. .vs 14
  2401. Releases 2.00 and R2.1 of the AT&T C++ Translator have a few bugs that we had to insert 
  2402. work-arounds for in the NIH Class Library.  These are conditionally compiled based 
  2403. on the definition of preprocessor symbols beginning with \fCBUG_\fR.  If you are using the 
  2404. NIH Class Library to test a Release 2.00 or 2.1 -compatible C++ compiler, we suggest 
  2405. that you edit the master \fCMakefile\fR to define these symbols:
  2406. 'in 72p
  2407. .br
  2408. .ad l
  2409. 'ft C
  2410. .ps 10
  2411. .OC
  2412. .sp 1
  2413. .vs 12
  2414. # Disable AT&T R2.0/R2.1 bug work-around code
  2415. .OC
  2416. .br
  2417. #BUGDEFS =
  2418. .OC
  2419. .br
  2420. BUGDEFS = -DBUG_bC2728 -DBUG_38 -DBUG_39 -DBUG_OPTYPECONST
  2421. 'in 36p
  2422. .ad b
  2423. 'ft R
  2424. .ps 12
  2425. .HE
  2426. .br
  2427. .ad l
  2428. 'ft B
  2429. .ps 14
  2430. .OC
  2431. .sp 2
  2432. .vs 16
  2433. YACC STACK OVERFLOWS
  2434. .ad b
  2435. 'ft R
  2436. .ps 12
  2437. .OC
  2438. .sp 1
  2439. .vs 14
  2440. The preprocessor symbol \fCBUG_TOOBIG\fR controls compilation of code we had to insert to 
  2441. avoid "yacc stack overflow" errors in the SunOS 3.5 C compiler.  Release 2.0 produces 
  2442. very complicated expressions for the inline copy constructors it generates for deeply-derived 
  2443. classes.  Explicitly defining non-inline copy constructors solves the problem.  If 
  2444. you are a C compiler vendor, please make your tables big enough to handle the C code 
  2445. generated by the AT&T C++ Translator!
  2446. .HE
  2447. .br
  2448. .ad l
  2449. 'ft B
  2450. .ps 14
  2451. .OC
  2452. .sp 2
  2453. .vs 16
  2454. COMPILING UNDER AT&T C++ TRANSLATOR RELEASE 2.1
  2455. .ad b
  2456. 'ft R
  2457. .ps 12
  2458. .OC
  2459. .sp 1
  2460. .vs 14
  2461. R3.0 of the NIH Class Library has been tested with Release 2.1 of the AT&T C++ Translator 
  2462. under SunOS 4.0.  The following subsections summarize the changes required when compiling 
  2463. with R2.1.
  2464. .HE
  2465. .br
  2466. .ad l
  2467. 'ft B
  2468. .OC
  2469. .sp 1
  2470. Inconsistent declarations of alloca() in header files
  2471. .ad b
  2472. 'ft R
  2473. .OC
  2474. .sp 1
  2475. The header files supplied with R2.1 declare \fCalloca()\fR with a return type of \fCvoid*\fR in \fC
  2476. alloca.h\fR and \fCchar*\fR in \fCmalloc.h\fR, so you get an error message from the compiler when 
  2477. both of these files are included in the same compilation unit.  We solved this problem 
  2478. by changing the return type of the declaration of \fCalloca()\fR in \fCmalloc.h\fR to \fCvoid*\fR.
  2479. .HE
  2480. .br
  2481. .ad l
  2482. 'ft B
  2483. .OC
  2484. .sp 1
  2485. Warning and error messages due to #pragmas in SunOS 4.0 header files
  2486. .ad b
  2487. 'ft R
  2488. .OC
  2489. .sp 1
  2490. The C compiler occasionally issues warning messages such as the following when compiling 
  2491. the output of the AT&T C++ Translator (both R2.0 and R2.1) under SunOS 4.0:
  2492. 'in 72p
  2493. 'll \n(.lu-(36p)
  2494. .OC
  2495. .sp 1
  2496. "/usr/include/CC/sys/signal.h", line 38: warning: function name expected
  2497. 'in 36p
  2498. 'll \n(.lu-(-36p)
  2499. .OC
  2500. .sp 1
  2501. This is because C++ doesn't understand the \fC#pragma\fR directives it encounters in some 
  2502. system header files,  so it just passes them through to the C compiler.  The warning 
  2503. message results because C++ eliminates or moves the C function declarations that the \fC
  2504. pragma\fR references.  Another problem is that the C++ header files use \fC#define\fR to temporarily 
  2505. rename system functions when they include the vendor's C header files as a way to hide 
  2506. the effects of the vendor's C declarations for these functions.  Unfortunately, this 
  2507. garbles the function names in the \fC#pragma\fR directives also.
  2508. .OC
  2509. .sp 1
  2510. Under R2.0, the \fC#pragma\fR problem just results in warning messages, but under R2.1, 
  2511. the C compilation occasionally fails with an error message.  We manually made a new, 
  2512. self-contained version of \fC/usr/include/CC/setjmp.h\fR with the following \fCpragma\fR at the 
  2513. end:
  2514. 'in 72p
  2515. .br
  2516. .ad l
  2517. 'ft C
  2518. .ps 10
  2519. .OC
  2520. .sp 1
  2521. .vs 12
  2522. /*
  2523. .OC
  2524. .br
  2525.  * Routines that call setjmp have strange control flow graphs,
  2526. .OC
  2527. .br
  2528.  * since a call to a routine that calls resume/longjmp will eventually
  2529. .OC
  2530. .br
  2531.  * return at the setjmp site, not the original call site.  This
  2532. .OC
  2533. .br
  2534.  * utterly wrecks control flow analysis.
  2535. .OC
  2536. .br
  2537.  */
  2538. .OC
  2539. .br
  2540. #pragma unknown_control_flow(sigsetjmp, setjmp, _setjmp)
  2541. 'in 36p
  2542. .ad b
  2543. 'ft R
  2544. .ps 12
  2545. .OC
  2546. .sp 1
  2547. .vs 14
  2548. This eliminates the error messages, but not the warning messages.  It would probably 
  2549. be no worse to simply remove the \fC#pragma\fRs altogether, since they don't seem to be having 
  2550. the intended effect, and that would eliminate the warning messages also.
  2551. .HE
  2552. .br
  2553. .ad l
  2554. 'ft B
  2555. .OC
  2556. .sp 1
  2557. C++ Translator +p option broken
  2558. .ad b
  2559. 'ft R
  2560. .OC
  2561. .sp 1
  2562. The +p option produces spurious errors under R2.1.  Edit the master \fCMakefile\fR to not 
  2563. use the +p option when compiling with R2.1:
  2564. 'in 72p
  2565. .br
  2566. .ad l
  2567. 'ft C
  2568. .ps 10
  2569. .OC
  2570. .sp 1
  2571. .vs 12
  2572. # C++ flags
  2573. .OC
  2574. .br
  2575. # NOTE: Disable +p option when compiling with AT&T R2.1
  2576. .OC
  2577. .br
  2578. #CCFLAGS = +p
  2579. .OC
  2580. .br
  2581. CCFLAGS =
  2582. 'in 36p
  2583. .ad b
  2584. 'ft R
  2585. .ps 12
  2586. .HE
  2587. .br
  2588. .ad l
  2589. 'ft B
  2590. .OC
  2591. .sp 1
  2592. .vs 14
  2593. Optional support for nested types
  2594. .ad b
  2595. 'ft R
  2596. .OC
  2597. .sp 1
  2598. You can optionally define the preprocessor symbol \fCNESTED_TYPES\fR to cause the NIH Class 
  2599. Library to use nested types under R2.1.  Edit the master \fCMakefile\fR as follows:
  2600. 'in 72p
  2601. .br
  2602. .ad l
  2603. 'ft C
  2604. .ps 10
  2605. .OC
  2606. .sp 1
  2607. .vs 12
  2608. # Compile with nested types (works with AT&T R2.1 and GNU C++)
  2609. .OC
  2610. .br
  2611. #NESTED_TYPES =
  2612. .OC
  2613. .br
  2614. NESTED_TYPES = -DNESTED_TYPES
  2615.